home *** CD-ROM | disk | FTP | other *** search
/ Visual Cafe 3 / Visual Cafe 3.ISO / Vcafe / Source.bin / WizardController.java < prev    next >
Text File  |  1998-08-21  |  9KB  |  314 lines
  1. /*
  2.  * WizardController.java
  3.  */
  4.  
  5. package symantec.itools.awt;
  6.  
  7. import java.awt.Component;
  8.  
  9. /**
  10.  * The WizardController interface provides a way to define a
  11.  * customized control of a Wizard.
  12.  * <p>
  13.  * The SimpleWizardController implements the basic default
  14.  * behavior for this interface.
  15.  *
  16.  * @see symantec.itools.awt.SimpleWizardController
  17.  */
  18.  
  19. public interface WizardController
  20. {
  21.     /**
  22.      * Constant wizard action value.
  23.      * @see #preparePage
  24.      * @see #validatePage
  25.      */
  26.     public final static int PREVIOUS = 0;
  27.     /**
  28.      * Constant wizard action value.
  29.      * @see #preparePage
  30.      * @see #validatePage
  31.      */
  32.     public final static int NEXT = 1;
  33.     /**
  34.      * Constant wizard action value.
  35.      * @see #preparePage
  36.      * @see #validatePage
  37.      */
  38.     public final static int FINISH = 2;
  39.     /**
  40.      * Constant wizard action value.
  41.      * @see #preparePage
  42.      * @see #validatePage
  43.      */
  44.     public final static int CANCEL = 3;
  45.     /**
  46.      * Constant wizard action value.
  47.      * @see #preparePage
  48.      * @see #validatePage
  49.      */
  50.     public final static int HELP = 4;
  51.  
  52.     // Life cycle
  53.  
  54.     /**
  55.      * Called before the first page is shown.
  56.      * Default behavior: none.
  57.      */
  58.     public abstract void doPrepare();
  59.  
  60.     /**
  61.      * Called before a page is shown.
  62.      * Default behavior: add the page to the history stack if the action is
  63.      * NEXT, remove the last page from the history stack if the action is
  64.      * PREVIOUS.
  65.      *
  66.      * @param comp
  67.      * The page that will be shown.
  68.      * @param action
  69.      * The action that has led to this page, either PREVIOUS or NEXT. If it is
  70.      * the first page of the wizard, the action is NEXT.
  71.      * @see #getPreviousPage
  72.      */
  73.     public abstract void preparePage(Component comp, int action);
  74.     /**
  75.      * Called after a page is shown.
  76.      * Default behavior: none.
  77.      *
  78.      * @param comp
  79.      * The page that has been shown.
  80.      */
  81.     public abstract void pageShown(Component comp);
  82.     /**
  83.      * Try to validate a page.
  84.      * Default behavior: return the state of the button associated with
  85.      * the action, using the isXxxEnabled methods. For example, if the
  86.      * controller has the Previous button enabled, this method will return
  87.      * true, meaning that it is valid to go back.
  88.      * If the result is true, then the Wizard will proceed with the
  89.      * action, else the state will not change.
  90.      *
  91.      * @param comp
  92.      * The page that must be validated.
  93.      * @param target
  94.      * The page that will be shown if the action is PREVIOUS or NEXT, null
  95.      * otherwise.
  96.      * @param action
  97.      * The action that must be validated, PREVIOUS, NEXT, FINISH, CANCEL or HELP.
  98.      * @return
  99.      * True if the action is validated, false otherwise.
  100.      */
  101.     public abstract boolean validatePage(Component comp, Component target, int action);
  102.     /**
  103.      * Called before the page is hidden.
  104.      * Default behavior: none.
  105.      *
  106.      * @param comp
  107.      * The page that has been shown.
  108.      */
  109.     public abstract void pageHidden(Component comp);
  110.  
  111.     /**
  112.      * Called when the FINISH action has been validated.
  113.      * Default behavior: none.
  114.      */
  115.     public abstract void doFinish();
  116.     /**
  117.      * Called when the CANCEL action has been validated.
  118.      * Default behavior: none.
  119.      */
  120.     public abstract void doCancel();
  121.     /**
  122.      * Called when the HELP action has been validated.
  123.      * Default behavior: none.
  124.      */
  125.     public abstract void doHelp();
  126.  
  127.     // State
  128.  
  129.     /**
  130.      * Tells if the Previous button must be enabled.
  131.      * Default behavior: return true if the getPreviousPage method
  132.      * returns a page, false otherwise.
  133.      *
  134.      * @return
  135.      * True if the Previous button must be enabled, false otherwise.
  136.      */
  137.     public abstract boolean isPreviousEnabled();
  138.     /**
  139.      * Tells if the Next button must be enabled.
  140.      * Default behavior: return true if the getNextPage method
  141.      * returns a page, false otherwise.
  142.      *
  143.      * @return
  144.      * True if the Next button must be enabled, false otherwise.
  145.      */
  146.     public abstract boolean isNextEnabled();
  147.     /**
  148.      * Tells if the Finish button must be enabled.
  149.      * Default behavior: return true if the current page is the last page
  150.      * in the Wizard container.
  151.      *
  152.      * @return
  153.      * True if the Finish button must be enabled, false otherwise.
  154.      */
  155.     public abstract boolean isFinishEnabled();
  156.     /**
  157.      * Tells if the Cancel button must be enabled.
  158.      * Default behavior: return true.
  159.      *
  160.      * @return
  161.      * True if the Cancel button must be enabled, false otherwise.
  162.      */
  163.     public abstract boolean isCancelEnabled();
  164.     /**
  165.      * Tells if the Help button must be enabled.
  166.      * Default behavior: return false.
  167.      *
  168.      * @return
  169.      * True if the Help button must be enabled, false otherwise.
  170.      */
  171.     public abstract boolean isHelpEnabled();
  172.  
  173.     /**
  174.      * Return the previous page.
  175.      * Default behavior: if a previous page has been set with
  176.      * setPreviousPage, return this page. If a previous page index has
  177.      * been set with setPreviousPageIndex, return the associated page.
  178.      * Else, return the next to last element on the stack. If there is none,
  179.      * return null.
  180.      * This method is called before and after a validatePage, and by the
  181.      * default implementation of isPreviousEnabled.
  182.      *
  183.      * @return
  184.      * The previous page to show, null if there is none.
  185.      * @see #setPreviousPage
  186.      * @see #setPreviousPageIndex
  187.      * @see #preparePage
  188.      */
  189.     public abstract Component getPreviousPage();
  190.     /**
  191.      * Return the next page.
  192.      * Default behavior: if a next page has been set with
  193.      * setNextPage, return this page. If a next page index has
  194.      * been set with setNextPageIndex, return the associated page.
  195.      * Else, return the next page in the Wizard components order,
  196.      * page 0 if no page has been shown.
  197.      * If there is none, return null.
  198.      * This method is called before and after a validatePage, and by the
  199.      * default implementation of isNextEnabled.
  200.      *
  201.      * @return
  202.      * The next page to show, null if there is none.
  203.      * @see #setNextPage
  204.      * @see #setNextPageIndex
  205.      */
  206.     public abstract Component getNextPage();
  207.  
  208.     // Interactions
  209.  
  210.     /**
  211.      * Set an index for the previous page.
  212.      * This index is used by the default implementation of getPreviousPage.
  213.      * It is reset after a page has been shown.
  214.      *
  215.      * @see #getPreviousPage
  216.      * @see #resetChainInfo
  217.      */
  218.     public abstract void setPreviousPageIndex(int index);
  219.     /**
  220.      * Set an index for the next page.
  221.      * This index is used by the default implementation of getNextPage.
  222.      * It is reset after a page has been shown.
  223.      *
  224.      * @see #getNextPage
  225.      * @see #resetChainInfo
  226.      */
  227.     public abstract void setNextPageIndex(int index);
  228.  
  229.     /**
  230.      * Set a previous page.
  231.      * This page is used by the default implementation of getPreviousPage.
  232.      * It is reset after a page has been shown.
  233.      *
  234.      * @see #getPreviousPage
  235.      * @see #resetChainInfo
  236.      */
  237.     public abstract void setPreviousPage(Component comp);
  238.     /**
  239.      * Set a next page.
  240.      * This page is used by the default implementation of getNextPage.
  241.      * It is reset after a page has been shown.
  242.      *
  243.      * @see #getNextPage
  244.      * @see #resetChainInfo
  245.      */
  246.     public abstract void setNextPage(Component comp);
  247.  
  248.     /**
  249.      * Enables or disables the Previous button.
  250.      * @param status <code>true</code> to enable the button
  251.      *
  252.      * @see #setNextEnabled
  253.      * @see #setFinishEnabled
  254.      * @see #setCancelEnabled
  255.      * @see #setHelpEnabled
  256.      */
  257.     public abstract void setPreviousEnabled(boolean status);
  258.  
  259.     /**
  260.      * Enables or disables the Next button.
  261.      * @param status <code>true</code> to enable the button
  262.      *
  263.      * @see #setPreviousEnabled
  264.      * @see #setFinishEnabled
  265.      * @see #setCancelEnabled
  266.      * @see #setHelpEnabled
  267.      */
  268.     public abstract void setNextEnabled(boolean status);
  269.  
  270.     /**
  271.      * Enables or disables the Finish button.
  272.      * @param status <code>true</code> to enable the button
  273.      *
  274.      * @see #setPreviousEnabled
  275.      * @see #setNextEnabled
  276.      * @see #setCancelEnabled
  277.      * @see #setHelpEnabled
  278.      */
  279.     public abstract void setFinishEnabled(boolean status);
  280.  
  281.     /**
  282.      * Enables or disables the Cancel button.
  283.      * @param status <code>true</code> to enable the button
  284.      *
  285.      * @see #setPreviousEnabled
  286.      * @see #setNextEnabled
  287.      * @see #setFinishEnabled
  288.      * @see #setHelpEnabled
  289.      */
  290.     public abstract void setCancelEnabled(boolean status);
  291.  
  292.     /**
  293.      * Enables or disables the Help button.
  294.      * @param status <code>true</code> to enable the button
  295.      *
  296.      * @see #setPreviousEnabled
  297.      * @see #setNextEnabled
  298.      * @see #setFinishEnabled
  299.      * @see #setCancelEnabled
  300.      */
  301.     public abstract void setHelpEnabled(boolean status);
  302.  
  303.     /**
  304.      * Reset the chain information set by setPreviousPageIndex,
  305.      * setNextPageIndex, setPreviousPage and setNextPage.
  306.      *
  307.      * @see #setPreviousPageIndex
  308.      * @see #setNextPageIndex
  309.      * @see #setPreviousPage
  310.      * @see #setNextPage
  311.      */
  312.     public abstract void resetChainInfo();
  313. }
  314.